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Developing good microcomputer software takes a great deal of 
time and energy. so the last thing you want to happen is to make 
such an investment in a program, only to have no one use it. The 
reasons for rejection are numerous. Perhaps your software is not 
easy to use, or the learning curve is to high. Maybe the reports 
are not flexible enough. or the manual is confusing. Whatever the 
reason, the result is the same: you will have wasted valuable time 
and energy on software that lies idle. 


The guide is designed to help you develop good software that 
people will enjoy using. It offers a comprehensive set of 
guidelines for developing user-friendly software that possesses 
consistent operating characteristics. Keyboard usage, represent- 
ing keystrokes in manuals, screen usage and presentation, error 
trapping, help functions, report formats and user guides — these 
are among the items covered. 


A common characteristic of the best personal computer programs 
being developed today is their “user-friendliness’: they are easy to 
learn, enjoyable to use and well documented. The original inten- 
tion of this guide was to help software developers within Deloitte 
Haskins & Sells to write such programs. We believe that, as more 
and more people invest in microcomputers to perform their daily 
work, good software is needed more than ever to take full advan- 
tage of the ever improving hardware. We trust that this book will 
go a long way towards providing guidelines for all software 
developers in designing programs which will be easy to learn and 
use. 


There are many different ways to design user friendly programs, 
and the choice of a particular approach or set of conventions is 
somewhat arbitrary. From a users viewpoint, however, life is 
much simpler if there are common elements in the different pro- 
grams he or she uses every day. By following the guidelines set 
out in this book. your programs will not only be used, but they 
will be used effectively. 


The recommendations in this guide are based on the extensive 
microcomputer experience of professionals in Deloitte Haskins & 
Sells. In preparation, we reviewed a number of different software 
packagés that are considered to have good user interfaces, and 


we analyzed software development guidelines used by companies 
such as IBM and Microsoft. The resulting recommendations are a 
blend of some of the best features we found. 


Throughout this guide we refer to the IBM Personal Computer 
(PC), which our organisation has selected as its standard micro- 
computer for software development. Nevertheless, many of the 
concepts presented are applicable to other microcomputers as 
well. A hypothetical microcomputer program called AuditPlan is 
used throughout to illustrate these concepts. 


The first edition of this guide was developed in our New York 
office, and consequently contains some American expressions and 
examples. We feel however, that these will not inhibit the com- 
prehension of the central concepts by the Australian reader. 


Keyboard Usage 


One of the greatest frustrations for any microcomputer user Is re- 
membering which key does what in which software package. There 
is nothing worse than pressing the F1 key, expecting to access the 
HELP function, and finding that you've just destroyed a data file 
you spent three hours creating! 


The most useful way to establish consistent operating characteris- 
tics for your software is through standardized keyboard usage. To 
the greatest degree possible, every key should perform the same 
function in each piece of software you write. With this objective in 
mind, let’s look at the problem as it applies to the IBM PC. 


Keyboard Layout 


Figure 1 is a diagram of the layout of the IBM PC keyboard. The 
keys can be grouped into four categories: 


e Ihe standard typewriter keys 
e |The numeric-keypad keys 

e The ten function keys 

e Special-purpose keys 


The standard typewriter keys are of little concern since their func- 
tion never changes: they are used to enter alphanumeric informa- 
tion into the computer. The numeric-keypad keys, designed for 
entering numeric data, would not normally be of concern either. 
With the IBM PC, however, these keys also have powerful cursor- 
control and editing functions. Most computer manufacturers pro- 
vide separate keys to handle these functions. IBM does not. There- 
fore, you must work around this design flaw when developing your 
software. 


The function keys are the most important to you as a software de- 
veloper, since they enable your users to access often-used func- 
tions, such as a HELP facility. The special-purpose keys—the ALT, 
CTRL, ESC, CAPS LOCK, PRTSC, NUM LOCK and SCROLL LOCK 
keys—are used for special microcomputer functions, such as con- 
trol codes, upper-case typing mode, numeric-keypad mode, system 
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termination and alternate character sets. They are important pri- 
marily because they can be used in conjunction with keys in the 
other groups and because their use varies widely in the micro- 
computer-software industry. 


FIGURE 1 —IBM PC KEYBOARD 
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Problems Caused by the Numeric Keypad 


The IBM PC’s numeric-keypad keys control two of the most com- 
monly needed functions on a microcomputer: entering numeric 
data and moving the cursor around on the screen. By defining the 
same keys for both purposes, IBM has created a problem for those 
who need both features in a software product. As a software devel- 
oper, you must determine how to overcome the problem. 


The solution lies in deciding just how important numeric-data en- 
try is to the particular piece of software you are developing. If it Is 
not that important, then don't worry about It. If it is, then you must 
allow users to enter data from the numeric keypad. 


Where numeric-data entry and cursor movement are equally impor- 
tant, you must work around the limitations of the keyboard. The so- 
lution lies in defining two sets of functions for the function keys. 
One set can be used when the numeric keypad is not needed, the 
other when it is. The latter set includes cursor-control and editing 
features. 


Defining the Function Keys 


The ten function keys on the IBM PC keyboard are programmable, 
enabling you, the programmer, to define what they do. Thus, you 
have an excellent means of building ease of operation into your 
software products. Like all other keys, however, the function keys 
must be used consistently from one program to another. 


The functions proposed for these ten keys are discussed below. 
Throughout the remainder of this guide, the two sets of functions 
will be referred to as system-control functions and edit functions. 


FIGURE 2—SYSTEM-CONTROL FUNCTIONS 
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F1 — Help 


The HELP function is designed to allow you to get help at any point 
in a program simply by pressing the F1 key. This function is most 
important in creating a user-friendly program. Accordingly, F1 is re- 
served for HELP under both definitions of the function keys. (The 
HELP function is discussed in more detail on pages 34-35) 


F2 — Erase Field/Clear Entry 


Anyone operating your software should be able to erase the con- 
tents of a field or clear the entry to any system prompt easily and 
quickly. The F2 key provides this capability. 
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F3 — Display Diskette Directory 


The F3 key enables you to determine the contents of the resident 
data diskette quickly. Most programs assume a Cefault disk drive 
for the data diskette or allow you to configure the system for this 
purpose. This function should determine which disk drive contains 
the data diskette and should provide the directory for it. The direc- 
tory function can be implemented as a complete screen rewrite or 
as a window. In either case, the directory should disappear when 
the ESC key is pressed. 


F4 — Return to Main Menu 


The F4 key allows you to escape instantly from a current task and 
return to the program's main menu without having to escape back- 
wards through every sub-menu. 


F5 to F8 — Undefined 


You can use these four keys to provide any system-related func- 
tions your imagination conjures. For example, you might want a 
function key that allows you to process and print a standard set of 
reports. 


FQ — UNDO Last Operation 


The FY key allows you to cancel the last action selected and restore 
the system and all data to their former status. For example, if you 
have just elected to post adjustments to a general-ledger file, the 
UNDO function will reverse the postings, leaving the general-ledger 
and the adjustments files in their original states. Note: An UNDO 
function can be very difficult to program: therefore, you should 
carefully consider whether the benefits outweigh the time and 
effort needed to implement the function. 


F10 — Exit System 


The F10 key permits you to exit from a program at any point during 
processing. The function must verify each request by asking for 
confirmation that you wish to leave. In addition, following verifica- 
tion, the function must update and close all program and data files 
before exiting to the operating system. 
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FIGURE 3—EDIT FUNCTIONS 
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-1 — Help 


This key performs the same function as that used when the numeric 
keypad is not required. 


-2 — Restore Field 


lf you have inadvertently typed over the entry in a field or a pre- 
vious response to a system prompt, the F2 key erases the new 
response and restores the old one. 


-3 — Line/Insert or Column/Left 


The F3 key allows you to insert a new line (above the line on which 
the cursor is positioned) into a file containing text. This function is 
needed only if the program you are developing has a rudimentary 
text-editing capability built into it. If your system has a DATA mode 
(which resembles data entry in an electronic spreadsheet), when it 
is in that mode you can use the F3 key to move the cursor one data 
column to the left. 


-4 — Line/Delete or Column/Right 


[he F4 key functions in the same manner as the FS key, except that 
pressing it deletes the line on which the cursor is positioned. In the 
DATA mode, you can use this key to move the cursor one data 
column to the right. 
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F5 — Character Insert 


To insert spaces into existing text so that additional characters can 
be typed, press the F5 key. You can perform this function only if 
there is room in the field for new characters. 


F6 — Character Delete 


The F6 key deletes the character at which the cursor Is currently 
positioned. Any characters to the right of the character being de- 
leted will automatically move left to fill in the space. 


F7 to F10 — Cursor Movement 


These four keys perform the normal cursor-movement functions of 
the arrow keys located on the numeric keypad: 


F 7 — Cursor Left F8 — Cursor Right 
F9 — Cursor Up F10 — Cursor Down 


When the numeric keypad is needed for data entry, these keys pro- 
vide the capability of moving the cursor easily while entering data. 


Implementing Both Function Sets 


In most cases, the software you are developing will need only one 
of the two function sets. Occasionally, however, the capabilities of 
both are required. 


To implement both function sets you must build the ability to 
change between them into your software. You should also include 
an indicator that identifies on the screen which set is in effect. To 
do this, use the SCROLL LOCK key as a toggle switch and place a 
function-status indicator on the right-hand side of line 25 on the 
display screen. (Figure 7 shows where the indicator is placed on 
the screen.) 


Whenever the SCROLL LOCK key is pressed, the function-key def- 
initions and the function-status indicator will change. This allows 
you to select the function set as needed at any point during pro- 
gram operation. 


In addition to changing function sets, you should be able to tempo- 
rarily access any single function in the other set without changing 
the complete function set. You can achieve this by allowing the 
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SHIFT key to work in combination with the function keys. For exam- 
ple, let's assume that you are in the EDIT function set and that you 
want to display the directory of the data diskette and then return 
immediately to your editing process. To view the directory, press 
F3 while holding down the SHIFT key. When you are finished with 
the directory, simply press the ESC key to return to the editing task. 


Use of Other Keys 


There are several other keys on the computer keyboard that should 
be used consistently from one program to the next: 


The ENTER Key 


The ENTER key should be used to enter a response to a system 
prompt or to enter a data item in a field on a full screen and move 
to the next field. It can also be used as a Carriage return in any 
TEXT EDITING mode you include in your software. 


The ESC Key 


The ESC key should always be used as an ESCAPE function, an es- 
sential ingredient in all software that you develop. Its purpose Is to 
provide a consistent means of “escaping from any operation—re- 
turning to a prior menu screen, terminating an operation in process 
and exiting from the HELP and DISPLAY DIRECTORY functions, for 
example. You must use care, however, to make sure that nothing 
catastrophic happens to any data files if the ESC key is pressed by 
mistake: your program should contain a code to*trap such errors. 


The BACKSPACE Key 


The BACKSPACE key should be used as a character-delete function 
rather than an alternate CURSOR LEFT function. When the BACK- 
SPACE key Is pressed, the character to the immediate left of the 
cursor Is deleted and all text to its right is shifted one space to the left. 


The DEL Key 


When the NUM LOCK key is off and the numeric keypad is func- 
tioning in the CURSOR MOVEMENT mode, the DEL key is used to 
delete the character at which the cursor is currently positioned. 
This works in the same way as the F6 key when the function keys 
are set in the EDIT mode. 
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The INS Key 


When the NUM LOCK key is off and the numeric keypad Is func- 
tioning in the CURSOR MOVEMENT mode, the!NS key is used to 
insert characters. It operates in the same manner as the insert func- 
tion in IBM BASIC; namely, when the INS key ts pressed, all charac- 
ters entered subsequently will be inserted until you press the INS 
key a second time. 


The HOME, END, PGUP and PGDN Keys 


These four keys should perform their normal functions: the HOME 
key should move the cursor to the top of a data stack or file; the 
END key should move the cursor to the bottom; and the PGUP and 
PGDN keys should move the data forward and backward, respec- 
tively, one full screen at a time. 


Other Keys 


To avoid confusion, you should not define special uses for any of 
the other keys on the PC keyboard. This is especially true for the 
CTRL and ALT keys when they are used in combination with the 
other keys on the keyboard. People have enough to do in learning 
to use software; they do not need the burden of having to under- 
stand two additional sets of keys. 


Summary 


As a program developer, you should strive to establish consistent 
keyboard functions. To the greatest degree possible, every key on 
the keyboard should perform the same function in every program 
you write. 


Screen Usage and Presentation 


Creating a uniform appearance for display screens is another im- 
portant consideration in developing software. This section exam- 
ines three types of screens: boot screens, program-identification 
screens, and active-display screens. It also looks at how your pro- 
gram interacts with users, with emphasis On the presentation of 
the active-display screen. 


Boot Screens 


A boot screen is the first display screen that appears when a pro- 
gram Starts running. Its primary purpose Is to provide basic pro- 
gram information (such as company name, program name, trade- 
mark and copyright) for legal purposes. A secondary purpose is to 
give the user something to look at while the first program modules 
are being loaded into the computer's memory. 


Ihe boot screen should be displayed only as long as it takes to load 
the initial program module— you don't want to bore people or to 
frighten them with threats about the penalties for copying your 
software. The key rule to follow in designing a boot screen is to 
keep it short and simple, like the sample below: 


FIGURE 4—BOOT SCREEN 


AuditPlan 


Deloitte Haskins & Sells 
11414 Avenue of the Americas 
New York, NY 10036 


(cle) 790-0500 


Copyright (C) 1984 by Deloitte Haskins & Sells 





15 


Screen Usage and Presentation 


Program-lidentification Screens 


The program-identification screen introduces users to your pro- 
gram and therefore offers you the opportunity to make a good first 
impression. The screen should accomplish two things: 


e It should immediately draw attention to the program name so 
that the user can easily determine if he or she has booted the 
wrong disk and, if so, gracefully exit before going further. 


e It should prompt the user to enter the proper date and time. 


Program Name 


The program name should stand out on the screen. You may want 
to exercise some artistic licence and present your users with a clev- 
erly designed graphics logo. Or you may choose simply to place the 
program name prominently on the screen. Accomplishing your 
goal through the first approach should not present a problem. The 
second, seemingly simple approach may actually be more difficult; 
however, displaying the program name in either the reverse- or 
highlighted-video mode should make it stand out sufficiently from 
the rest of the information on the screen. 


If you choose the artistic route, do not assume that your users have 
colour/graphics screens. Instead, design a logo that looks attractive 
on display devices with the most limited capabilities; it will be 
equally effective on more sophisticated equipment and will help 
you attract the largest user group possible. Another option is to 
have your program poll the operating system to find out what kind 
of display is present. Then you can provide different screens for 
each case. 


In addition to the program name, the program-identification screen 
should show the version number of the software. A sample follows: 
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FIGURE 5—PROGRAM-IDENTIFICATION SCREEN 


Version 3.2 


Current Date: 87/31/1984 
Current Time: 12:18:08 


(....System loading files 





Date and Time 


For the following reasons, It is important to enter the correct date 
and time into a program before doing anything else: 


« | he operating system assigns the date and time to all files that 
are created or updated during program processing. This ts most 
helpful in determining which version of a data file is saved ona 
diskette. 


« Your program can print the correct date and time on all reports. 
[his is most helpful in determining which version of a printout 
you are looking at. 


« If your program is designed to expire on a specific date, it should 
check the current date against the expiration date and issue a 
warning if the system has expired. 


System prompts for retrieving the date and time should be placed 
near the bottom of the display screen. (See the sample screen 
above for an example.) The program name or logo should remain 
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displayed. As the user enters the date and time, the program 
Should validate the responses to ensure that incorrect dates and 
times are not entered. 


Since many PCs have automatic, real-time clocks, your program 
Should have an option that allows the user to configure the soft- 
ware so that date and time information can be retrieved from the 
clock. The date can be verified by comparing it to a date embedded 
in the program (such as the date the program was written). If the 
date retrieved from the system Is later than the one embedded in 
the program, it is most likely correct. If it is earlier than the embed- 
ded date, your program should ask the user to enter the date and 
time separately. 


Active-Display Screen 


Once your users are past the boot screen and the program-identi- 
fication screen, they should always be working within a standard 
active-display screen. This should be partitioned into several sec- 
tions, as shown below in figure 6: 


FIGURE 6 —SECTIONS OF THE ACTIVE-DISPLAY SCREEN 


SECTION 1 SECTION ¢ 


SECTION 3 


SECTION 4 SECTION S 





[he IBM display screen has twenty-five rows and eighty columns, 
or character positions, within each row. Each of the sections above 
can be considered a window on the display screen. The boundaries 
of each window, along with the type of information that should be 
displayed therein, are given below: 


Section 1: Columns 1 through 27 of rows 1 through 3. Insert 
the firm's name here. 


Section 2: Columns 60 through 80 of rows 1 through 3. Use 
this section to display program name, application 
or client name and task name. 


Section 3: Columns 1 through 80 of rows 5 through 23. This is 
the actual working area. Display all menus, system 
prompts, most error messages, and user-definable 
system parameters here. If you think you need the 
entire screen space for some aspect of your program 
(i.e., HELP function screens), use it. To avoid confu- 
sion, however, limit such deviations from the recom- 
mended use. 


Section 4: Columns 1 through 59 of row 25. Use this section to 
display brief error messages that occur while you 
are selecting menu options, entering file names or 
entering responses to other system prompts. Exam- 
ples of such errors include: 


Illegal Keystroke File Does Not Exist 
Option Not Available Invalid Response 
Section 5: Columns 60 through 80 of row 25. Reserve this sec- 


tion for program-status indicators. Use the far right 
side to display the status of the function-key defini- 
tions. Use the words SYSTEM and EDIT, displayed 
in highlighted video, to indicate whether the sys- 
tem-control functions and the edit functions, re- 
spectively, are active. 


Consider including indicators for the CAPS LOCK 
and NUM LOCK keys to the left of the function in- 
dicator. For example, display the words CAPS or 
NUM, respectively, in highlighted video when these 
keys are pressed. 


Lis, 
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Regarding the general description of the active-display screen, 
please note: rows 4 and 24 should be solid lines across the entire 
display screen. The lines can be generated using the IBM PC ASCII 
character number 196 (hexadecimal C4). 


Example 


Figure 7 shows an active-display screen for the hypothetical Audit- 
Plan program. In section 4 of the screen, please note the error mes- 
sage. This was triggered by our hypothetical program user, who 
selected option 9 when there are only eight options (numbered 

1 through 8) available. 


FIGURE 7—ACTIVE-DISPLAY SCREEN 


















Deloitte AuditPlan 
Haskins+Sells Colligan's Micros Inc. 


MAIN MENU 


Audit Planning 

Audit Administration 
Internal Control 
Transaction Testing 
Balance Testing 
Reports 

Other Tools 
Housekeeping 


Onl a tr ew Me 


OPTION 77 









Press ESC to return to previous screen. 


OPTION NOT AVAILABLE CAPS NUN SYSTEM 
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Screen Presentation During Program Operation 


As you can see, AuditPlan is menu driven, enabling the user to 
view all the options available at any point during program opera- 
tion. After the user selects an option the program presents a set of 
sub-options in a sub-menu. The first menu presented by the pro- 
gram is known as the main menu. 


The user continues selecting options from various levels of sub- 
menus until the program has all the information required to process 
the primary task selected from the main menu. Then the program 
returns to the last sub-menu from which an option was selected. 
The user can elect either to back up through the sub-menus by 
repeatedly pressing the ESC key or to return directly to the main 
menu by pressing the F4 key from the system-control functions. 


Menu-driven software is popular because it is easy to use. However, 
it can frustrate the experienced user who wants to proceed directly 
to a task without wading through a number of different menu 
levels. Ways to alleviate this frustration are discussed on page 26: 
here we present some general principles to follow when developing 
menu-driven software. 


Consistent Placement of Menu Text 


To make your software as easy to use as possible, all menus and 
sub-menus should be uniform in design and screen placement. In 
addition, you should strive for crisp, clean, uncluttered menus. 
Figure 8, which depicts a display screen's work area, is designed to 
meet these objectives. 


General Guidelines for Menus 


e Use as few menu levels as possible. Ideally, there should be no 
more than three sub-menus. 


« Use no more than eight options on any menu. Reading more than 
eight takes too much time. 


« Make option names as brief, yet descriptive, as possible — prefer- 
ably, no more than two words. 


e Do not display any options on the screen that cannot be selected 
because of processing status or application requirements. 


Screen Usage and Presentation 


e Allow users to select options by a single keystroke. Users should 
not have to press the ENTER key to complete a menu selection. 
The required keystroke can be either the number of the menu 
option or the first letter of the option name. If you decide on the 
latter, be careful not to duplicate the first letters on your menu 
options. | 


e Use the ESC key to back up to a previous menu. 


FIGURE 8—PLACEMENT OF MENU TEXT 
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Screen Appearance During Processing 


At some point, your program will need to process the data given it. 
Because the time required for this step can vary greatly, it is impor- 
tant to keep the user informed, especially if a lengthy process is an- 
ticipated. Some guidelines follow: 


« If processing is expected to be short, the screen should display a 
message indicating that this task is taking place and asking the 
user to wait. Clear section 3 of the active-display screen and dis- 
play the following message in the centre: 


PROCESSING .... PLEASE WAIT 


- If processing Is expected to be lengthy, the user should also be 
given a progress report. For example, if the user is sorting a file 
that contains 100 records, the program can display a counter 
showing the number of records sorted. Or it can show the 
passage of time by displaying dots in a line across the screen. 
Another dot can be added every five to ten seconds to indicate 
that processing is continuing. On the screen, you might see 
something like: 


PROCESSING .... PLEASE WAIT 


Program Wrap-Up 


You must make certain that your program addresses all the loose 
ends that must be tied when users decide to exit. The program 
must: 

« Update and close all data files. 


« Verify the user's request to leave the system before he or she 
does So. 


« Clear the entire screen upon verification and place the cursor tn 
the home position before exiting to the operating system. 
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Screen Usage and Presentation 


Advanced Screen Techniques 


To achieve the minimum acceptable level of user friendliness, you 
Should include the items discussed in the last section in all your 
programs. A number of other techniques can further enhance user 
friendliness if they are used properly: special display modes, scroll- 
ing, Windows, menu selection by cursor and command sub-systems. 


Special Display Modes. There are three types of special display 
modes: reverse video, highlighted video and colour. They can effec- 
tively reduce the amount of time the user spends accomplishing a 
task with your software, but they should be used judiciously and 
for one reason Only: to draw attention to a particular portion of the 
display screen. 


To achieve this objective and ensure maximum efficiency, you 
must resist overusing these techniques. Getting carried away with 
them will only confuse your users. Here are two guidelines: 


e Use special display techniques on/y when you need to draw at- 
tention to a desired response. For example, in figure 7 (the main 
menu for AuditPlan) the system prompt OPTION ? is displayed in 
highlighted text. This draws attention to the fact that the system 
is waiting for the user to make a menu selection. 


e Give preference to highlighted video. It is more subtle than 
reverse video yet Is still sufficient to draw attention to a specific 
part of the screen. Since no special hardware is needed, high- 
lighted video is also preferred over colour video, which requires 
a colour terminal. 


Scrolling. The scrolling process, carried out with the cursor-move- 
ment keys, allows the user to view an entire data or text file that 
would not otherwise fit in the work area on the display screen. All 
of the cursor-movement keys on the numeric keypad — the four 
Cursor-arrow keys as well as the HO/JME, END, PGUP and PGDN 
keys— should be available to the user for controlling the display. 


Windows. Throughout this guide, the word window is used gener- 


ically to mean split screens, partial-screen overlays or full-screen 
overlays. In a split screen, the active-display screen is separated 
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into two or more sections so that different segments of data can be 
viewed at the same time. A partial-screen overlay is somewhat simi- 
lar but is generally used only for reference purposes. For example, 

if you are working on a text document and cannot recall the com- 
mand to move text, you can look up the information in a window 
that overlays a portion of the text screen. When you find the com- 
mand you want, simply press the ESC key: the window will disap- 
pear, restoring the section of text it had overlain. A full-screen over- 
lay works in the same way as a partial overlay, except that it re- 
writes the entire screen. 


Split screens and partial-screen overlays are very useful when you 
must display a great amount of data on the screen at one time. 
Split screens offer an effective means of organizing and separating 
the information on the screen; partial-screen overlays are effective 
when you must briefly refer to other information in the program. 


Use discretion in determining whether these two techniques will 
enhance your software. You don t want to confuse your audience 
by filling the screen with irrelevant information. You may be able to 
achieve your objective simply by adding another menu option. 


Split screens and windows, then, should be used only when neces- 
sary, for instance when you are implementing a HELP function. For 
a HELP function, which contains so much information that it is 
almost like a program within a program, you will generally need to 
use a full-screen overlay. 


HELP functions—and how they should be implemented — are cov- 
ered more fully later in this guide. 


Menu Selection by Cursor. The single-keystroke approach for se- 
lecting options from menus has already been discussed. Another 
popular method involves using the cursor to point to the desired 
option, and then pressing the ENTER key. 


I his approach should supplement— not replace — the single- 
keystroke method. A typical user session implementing this ap- 
proach might occur as follows: 


e Ihe user is presented with a menu screen like the one shown 
earlier for AuditPlan (figure 7). The system pgpmpt OPTION ? is 
displayed tn highlighted video. 
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Screen Usage and Presentation 


e If the user presses the CURSOR DOWN key, the first option in 
the menu changes from normal to highlighted video. 


e If the user then presses the ENTER key, the first option will be 
selected. But if the user presses either the CURSOR UP or the 
CURSOR DOWN key instead, the first option in the menu returns 
to normal mode and the next option (above or below it, depend- 
ing on which CURSOR key was pressed) changes from normal to 
highlighted video. This action continues until the user either 
presses the ENTER key to select the highlighted option or enters 
an option number to select an option. 


Command Sub-Systems. As we have already stated, the experi- 
enced user generally dislikes menu-driven systems with numerous 
menu levels. You can alleviate this frustration somewhat by limiting 
the number of sub-menus to three. Or you can avoid the problem 
by building a complete command structure into your program. This 
allows the user to enter a task name and proceed directly to It with- 
out wading through intermediary menus. Implementing a com- 
mand structure on top of a menu-driven system can be very tricky, 
however. Consider using the following approach: 


e Define the F5 key in your system-control functions as an ENTER 
COMMAND function. 


e If the user presses the F5 key when the prompt OPTION ? is dis- 
played, a new prompt should appear. This prompt should read 
ENTER COMMAND ?. 


e If the user then enters a direct command, your program should 
take him or her directly to the menu needed to carry out the 
command. 


Before implementing this type of command structure, you should 
carefully consider whether the programming effort will be worth 
the benefits. If you decide to proceed, be sure to include a com- 
mand reference section in your user guide to explain the function 
and effect of every available system command. 
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Other Comments 


Another characteristic that will affect the users perception of the 
quality of your program is screen speed—the rate at which screens 
appear, change or are cleared by your program. Jerky, clumsy 
screens that appear slowly have no appeal compared with those 
that snap quickly and sharply to attention. 


Implementing effective screens is not difficult; it simply requires a 
little research. Peter Norton's /nside the IBM PC. Access to Aa- 
vanced Features and Programming (Bowie, Maryland: Robert J. 
Brady Company, 1983) sheds much light on the inner workings of 
the IBM PC and should be consulted before undertaking any large 
IBM PC programming task. Of special note, chapters 8 and 9 cover 
video techniques and how to implement them. 


Norton recommends building screens in an unused part of mem- 
ory, and then using a memory-shift command to relocate them to 
the video-display card when needed. Taking this concept one step 
further, you can build your screens in advance and save them ona 
diskette as binary images. You can load them into RAM from the 
diskette and then shift them to the video screen as needed. This 
technique makes It easy for you to change your screens in the 
future without modifying your program, a useful capability whether 
for simple updates or for more ambitious tasks —implementing 
foreign-language versions of your program, for example. 


Summary 


Following simple guidelines for designing uniform screens and 
adopting consistent operating procedures will go far towards cre- 
ating software that is truly user friendly. And these basics can be 
enhanced with the more advanced techniques discussed: special 
display modes, scrolling, windowing, menu selection by cursor and 
command sub-systems. 
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Data-Input Methods 


Without data, a computer program is a mere collection of meaning- 
less instructions. There are four major methods of giving computer 
programs data to work with: interactive, full screen, soreadsheet 
and external files. 


interactive 


The interactive data-entry method is commonly used for timeshar- 
ing systems. Following a question-and-answer format, the computer 
program asks the user for information, and he or she provides the an- 
swers until the program has enough data to act on. 


This method is rarely used for microcomputer software, primarily 
because the powerful screen functions available on microcomput- 
ers provide more elegant ways to display data. There are instances 
when the interactive method is useful, however. Here are some 
guidelines: 


e Use this method primarily when minimal information is needed 
by the program. Entering the date and time from the program- 
identification screen is a good example. 


e If you choose to use this method when more extensive data entry 
is required, always begin with a clear work area. This means that 
section 3 of the active-display screen should be cleared before 
the data-entry session begins. 


e Thesystem prompts and questions should be clear and concise. 


e The editing functions should be available to modify the user's re- 
sponse before he or she tells the program to accept It. 


e Ihe users response should be sent to the program when he or 
she presses the ENTER key. 


Using the guidelines above, figure 9 shows an example of an inter- 
active session for AuditPlan. For purposes of this illustration, all of 

the computer prompts and questions, have been printed in capital 

letters. User responses are shown in green. 


28 


| IGURE J—INTERACTIVE DATA ENTRY 
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Full Screen 


Ihe full-screen entry method achieves the same result as the inter- 
active method but yields a more striking product. Here, input re- 
quirements are grouped into data-collection forms; each form is 
placed on the screen, enabling the user to enter the information 


requested by It. 


| hroughout this process, all of the editing functions are available, 
and the user can move freely around the data-input areas. This 
makes tt easy for the user to execute any corrections or changes 
needed before telling the program that he or she has completed 
the form. At that point, the user presses a designated key that sig- 
nals the program to process the data. 
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Data-Input Methods 


Below are some guidelines for using the full-screen data-entry 
method in your programs. Figure 10 illustrates the full-screen 
method using the same example shown in figure 9. The brackets 
indicate the input area for each field on the form. 


e The full-screen form is the preferred method for direct data entry, es- 


pecially for large amounts of data. There are some exceptions to this 
rule, however: 


When only a minimal amount of information, such as date and 
time, is needed, it is easier and more convenient to use the inter- 
active method. 


When the system prompt requests a task, a Menu option, a “yes” 
or “no’ confirmation to a requested action, a disk-drive letter, a 
file name or the like, the interactive method ts best. 


When there is a large amount of quantitative data, the spread- 
Sheet data-entry method is more suitable. 


When data can be input directly from the files of another 
program. 


e Thecursor control and all editing keys should be available to edit 


the information being entered into the data-collection form. 


e When the user completes an entry to an input area, he or she 
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Should simply press the ENTER key to move to the next field. 


Define the F6 key, from the four available SYSTEM function keys, 
as an ACCEPT FORM function so that when the user has com- 
pleted the data-collection form, he or she can signal the program 
to move On. 


FIGURE 10—FULL-SCREEN DATA ENTRY 






















Deloitte AuditPlan 
Haskins+Sells Colligan's Micros Inc. 
Client Profile 


CLIENT NAME = {Colligan's Micros Inc. } 
YEAR END (MN-DD-YYYY) = {}2-3)-1984) 
CLIENT ADDRESS = {£25 Fourth Avenue South } 
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INDUSTRY = {Electronic Components } 


AUDIT FEES FOR 1583 : {75000 } 
L48e + {45000 } 
981: {£2500 4} 


PRESS Fb TO ENTER FORM AND MOVE ON. ESC TO END. 
CAPS NUM 





SYSTEM 





Spreadsheet 


Spreadsheet data entry derives its name from the electronic spread- 
sheet programs, like VisiCalc and Lotus 1-2-3, that emerged in the 
early 1980s. These programs use a data-entry technique that is par- 
ticularly well suited for entering large amounts of quantitative infor- 
mation, such as you might find in accounting reports or financial 
forecasts. 


Ihe spreadsheet consists of a series of columns and rows. The in- 
tersection of any row and column is called a ce// A single data item 
can be entered into each cell by typing the information and then 
pressing the ENTER key to “attach’ it to the cell. 
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Data-Input Methods 


Here are some guidelines for using spreadsheet data entry in your 
programs: 


The cells must be wide enough to accommodate the largest 
number your program is designed to handle. 


Row and column titles should appear as references on the screen. 


In many instances section 3 of the active-display screen will not 
be adequate to efficiently handle the large amount of data usually 
associated with spreadsheet entry. If this is the case with your 
software, use a full-screen overlay. 


The columns and rows Should scroll as needed so the user can 
adjust the portion of the worksheet area he or she Is viewing. 


Use the ENTER key to attach the entry to a cell. 


With the EDIT functions active, use theF3 andF4 keys to change 
columns and the F9 andF 10 keys to change rows. 


Use the F6 key (SYSTEM function mode) to complete the spread- 
sheet data-entry mode and the ESC key to abort the spreadsheet 
data-entry/edit process. 


Following these guidelines, figure 11 shows a sample spreadsheet 
data-entry screen (using section 3 of the active-display screen) for 
AuditPlan. 
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FIGURE 11—SPREADSHEET DATA ENTRY 
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External File 


In many cases data needed for a program will already exist for 
other programs being used. In such instances, rather than retype 
the data, users will want to input the information directly from 
these other program files. This method of data entry is called 
external-file data entry and will be discussed in more detail later 
in the guide. 
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Help Function 


Any program that claims a high degree of user friendliness must 
have some level of HELP function built into it. HELP functions, how- 
ever, vary widely from program to program. This section reviews 
two types: the first is the Rolls Royce—a fully integrated HELP 
function—and the second is the minimum HELP function accept- 
able for your programs. 


Determining which type to use in a program is a subjective deci- 
sion, but it should be based on the function and complexity of the 
program. For example, if you write a program to compound simple 
interest over the life of a loan, a complex HELP function is unneces- 
Sary because the program is uncomplicated and self-explanatory. 
However, if you write a program to perform financial modelling and 
consolidation for a wide range of clients, a fully integrated HELP 
function is almost a necessity. 


Fully Integrated HELP Function 


A fully integrated HELP function should eliminate the need for a 
reference manual for your system. Properly implemented, it will: 


e Becompletely contextual. When the user presses the HELP func- 
tion key (F1) at any point in the program, the function should pro- 
vide topical information within the context of what he or she ts 
trying to do at that moment. 


e Provide a more general level of HELP, which should be controlled 
either by its own menu Structure or by an index to the various 
HELP topics. 


The Lotus 1-2-3 software package has these basic characteristics, 
and reviewing it may be worth your while. It is one of the best im- 
plementations of a fully integrated HELP function in any off-the- 
shelf software package. 


The Minimum-Level HELP Function 


A fully integrated HELP function is the most desirable method for a 
user-friendly software package. You may not have the time to de- 
sign and program such a facility, however. If not, what alternative 
do you have? 


Review the HELP functions in various off-the-shelf software prod- 
ucts to try to find a suitable approach for your own program. At a 
minimum, a HELP function should: 
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« Provide HELP information in a collection of screens that display 
general information about the system and its operation. 


« Allow viewing control with the PGUP, PGDN, HOME and END 
keys. (There would be no menu or index-controlling structure.) 


General Guidelines for HELP Functions 


Regardless of the type of HELP function you decide to build into 
your program, the following guidelines will help you implement 
it effectively: 


« HELP screens should overlay the entire display screen— not just 
a portion of it— to accommodate the large amount of information 
involved. 


- The information presented on HELP screens should be clear and 
concise to avoid “overloading” the screen (and your users) with 
confusing data. 


e Use highlighting to draw attention to the most important infor- 
mation, particularly if you cannot avoid overloading the screen. 
In addition, if you are writing your programs for colour, consider 
using it as a highlighting technique. 


- HELP screens should be saved on diskette as screen-image files 
and brought into the system only when needed. This will mini- 
mize maintenance and provide the capability to easily implement 
foreign-language versions of your program. In addition, screen 
speed will be much faster than if your program must “paint” them on 
the screen—and speed is critical to an effective HELP function. 


lf you do not include a HELP function in your program, make certain 
that your user guide contains all of the required HELP information 
in an easily accessible format. 


Summary 


In choosing a level of HELP function for your user-friendly software 
products, you must carefully weigh the costs of implementation 
against the benefits to the user. In most cases you will probably 
select a HELP function that falls between the two extremes— the 
minimum level acceptable and a fully integrated facility. 
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Error Trapping 


Like a HELP function, effective error trapping is essential for any 
software that claims to be user friendly. One of the most frustrating 
things for a beginner is to be kicked out of a program into the 
operating system, so your programs should be designed to trap all 
potentially catastrophic errors. To help ensure this, your debugging 
and field-testing stages should be rigorous enough to shake out 
any major bugs that remain in the program's error-trapping facility. 


This section highlights the types of errors for which your program 
Should be on the lookout and discusses how error messages should 
be written and presented on the screen. 


Types of Errors and Error Messages 


Four types of errors can occur while running a program: invalid key- 
stroke, invalid user response, system errors and compound errors. 
The type of error usually determines what kind of error message 
you should provide and where it should be presented on the screen. 


Invalid Keystroke 


An invalid keystroke is an error that occurs when you press the 
wrong key. For example, if you are entering numerical data into a 
Spreadsheet-type work area, any key other than 1,2,3,4, 5,6, 7, 
8, 9,0,.,- or + is an invalid keystroke and should not be accepted 
by the program. Because invalid keystrokes are rarely catastrophic, 
they do not warrant displaying an error message on the screen: a 
sound of the bell on the computer when they occur will suffice. If 
you follow this approach consistently throughout your program 
(and any other programs you develop), your users will always know 
when they ve pressed the wrong keys. 


Invalid User Response 


Although similar to an invalid keystroke, an invalid user response Is 
primarily concerned with user responses to system prompts. For 
example, when a user Is presented with a menu that has eight op- 
tions (numbered 1 through 8), his or her entry of 9 after the prompt 
OPTION ? is an invalid response. This type of error is illustrated in 
figure 7. 


For an invalid response, sounding the bell on the computer is not 
adequate to explain what is wrong. First of all, it would be easy to 
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assume that the error was an invalid keystroke, which also sounds 
the bell. Second, even if the user did realize that the program was 
complaining about something other than an invalid keystroke, he 
or she might not be able to pinpoint the problem. Accordingly, an 
invalid user response should always be accompanied by a message 
displayed on the screen. 


Messages should tell users what they did wrong and request that 
they reenter the responses. In most cases, the error message 
should be short and concise enough to be displayed in section 5 of 
your program's active-display screen. For example: 


OPTION NOT AVAILABLE 
RESPONSE MUST BE Y orN 
RESPONSE TOO LONG 


In addition to displaying the message, the program must erase the 
invalid response and reposition the cursor at the beginning of the 
response field so the user can enter a new response. In cases where 
ihe response is quite long, the user might find it easier to edit the 
original response than to set up a new one. To provide this capabil- 
ity, define the F2 key in the EDIT functions as a RESTORE FIELD op- 
eration. By pressing F2 the user can recall the old entry, edit it with 
ihe cursor-control keys and reenter it by pressing the ENTER key. 


System Errors 


System errors occur without any direct action by the user. Disk- 

(ile read/write errors, operating system errors and errors generated 
by program bugs are all considered system errors. Because they are 
inherently difficult to explain in a few words, your explanations 
probably will not fit into the space available in section 5 of the 
active-display screen. In this case, use the area below the OPTION ? 
prompt to display the message, but try to limit it to lines 22 and 23 
of the screen. 


Keep in mind that the message should be as concise as possible 
and should indicate what action is required to continue processing. 
For example, suppose the user had neglected to put a data diskette 
into disk drive B. Your system, upon trying to write to this diskette, 
discovers that it is not present and displays an error message as 
shown in figure 12. 
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Error Trapping 
FIGURE 12—SYSTEM ERROR MESSAGES 
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THE DATA DISKETTE IN DISK DRIVE B IS NOT READY. 
PLEASE CORRECT AND PRESS ANY KEY TO CONTINUE. 
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Compound Errors 


Sometimes several errors occur during the same process in the pro- 
gram. These are called compound errors. For example, many sys- 
tems, especially financial-modelling packages, use “rules” that you 
must specify. Because the rules are usually checked by the program 
all at once, rather than individually as they are entered, more errors 
can be generated than can be displayed On the screen at one time. 
If your program could generate errors in a similar fashion, you must 
provide a special means of handling them. 


Take a simple approach to this: for example, during processing, 
nothing special should be done unless an error Is actually encoun- 
tered. At that point, the program should interrupt processing, 
inform the user of the error and ask whether it should be listed on 
the screen or the printer. 
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If the user selects the screen, your program should clear the screen 
entirely, begin listing messages at the top left and continue sequen- 
tially until processing has been completed. After processing, the 
user should press the ESC key to return to a menu. Until the ESC 
key is pressed, the user can view the error messages with the 
cursor-control, HOME, END, PGUP and PGDN keys. 


lf the user selects the printer, no change tn the display screen 
Should take place. 


In addition to these options, you might consider displaying the 
error messages On both the screen and the printer. If you do this, 
the program should allow the user to view the errors on the screen 
after processing is completed and before he or she is ready to 
return to a menu. 


Other Guidelines for Presenting Error Messages 


e Use one of the special display techniques to highlight the error 
messages. The highlighted-video technique Is the most effective. 


e Do not use error messages that blink. Although they draw atten- 
tion to the screen, they can be very annoying. Highlighted or 
reverse video works just as effectively. 


« Error messages should reside in disk files, where they are easier 
to maintain, rather than be hard-coded into your program. This 
also makes it easier to implement foreign-language versions. 


Summary 


Good error trapping is essential to user-friendly software. If pre- 
sented effectively and consistently, the four types of error mes- 
Sages— Invalid keystrokes, invalid responses, system errors and 
compound errors— should guide users in correcting mistakes and 
proceeding with your program. 
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Printer Support 


Many printers are available for microcomputers, each differing from 
the others, often only slightly as to particular features. However, if you 
make certain assumptions about the printers that your users will have 
attached to their computers, these differences may cause your pro- 
gram’s reports to look poor. 


There are many printer-dependent features— condensed printing, 
emphasized printing and printing with different type fonts, for 
example—and the means of implementing these features often 
vary with the printer. It is therefore difficult to support such features 
in your programs. You must Strive for an acceptable level of support 
that allows some degree of flexibility. Here are some guidelines: 


e For the IBM Personal Computer, it makes sense to support the 
IBM printer. IBM's standard dot-matrix printer is an Eoson MX-80 
series; therefore, your program should support both the IBM and 
Epson printers. 


e Do not use special print techniques that may be unique to one 
printer. For example, condensed and expanded typefaces, Italics, 
multiple type fonts, subscripts and superscripts are available 
only on certain printers. Avoid using these techniques. 


e Certain printer features should be supported in your software 
through a printer configuration menu. In particular, programs 
should allow you to define the following: 


Page width— to accommodate wider printers. 


Page length— to accommodate paper of different sizes. This is 
particularly important when developing software products for 
international use. 


Sending control codes—so users can set up printer control 
strings. Use hexadecimal control codes (they take up less file 
space when saved) and require that codes be preceded by the 
symbol ~, which helps separate multiple control codes and iso- 
late those that might be embedded in other textual information. 
With this approach, a control string might appear as follows: 


*46°72°61°6E°6B 
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Hex code for form feeds — to signal a form feed to the top of a new 
page. By allowing users to specify this code, you can write your soft 
ware without worrying about counting print lines. Your software 
should provide the ASCII form-feed code, hexadecimal (OC) as the 
default setting. 


Special hex codes—so users can specify the hex codes needed 
for compressed and enlarged print modes, if these are essential 
for your software. Default settings should be those used by the 
Epson MX-80 series of printers. 


- If you must use a printer-dependent feature in your program, the 
user guide should specify the kind of printer that may be needed 
to run the software. For example, if your program supports high- 
resolution graphs and charts, an Epson graphics printer may be 
needed. 
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Standard Report Formats 


The type of software you are developing will determine whether 
you will want to provide standard reports. For example, if you are 
writing a program that will allow people to make sophisticated 
financial forecasts and consolidations, your users will also want the 
flexibility to design their own reports; your program must give 
them the means to do so. You may also want to give them a small 
set of default reports that can be used when they don't need any- 
thing more sophisticated. 


Your primary objective in designing standard reports is to make 
them as useful as possible. They must be well laid out, the infor- 
mation in them should be presented in a logical manner, and they 
should not be cluttered and difficult to read. In addition, standard 
reports should include: 


The date and page number on every page of the printout. 


The time at which the report was printed (if your software pro- 
duces time-critical information). Printing the time on the report 
pages helps in distinguishing between different versions of the 
same printed report. 


The name of the program and the release number (if your soft- 
ware is to be used for engagement-related purposes). This infor- 
mation should print on the first page of the report. 


When designing reports you should also consider the following: 


Lay out reports that are prepared for the firm's use in a size that 
conforms to the standard width of audit working papers. This will 
eliminate the need to fold printouts for filing. 


Avoid using special printer functions like condensed and en- 
larged typefaces. If you must use them, follow the guidelines 
given in the preceding section. 


Avoid counting lines for pagination whenever possible. Use the 
top-of-form function instead; it is much more efficient, and your 
program will be easier to maintain. 


Use page breaks logically. They can be a very effective means of 
organizing the information contained in the report. 
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As microcomputer use grows, security is becoming an increasingly 
important issue. This is particularly true for the IBM PC XT witha 
hard disk. To maintain physical control over the data on the hard 
disk, you must be able to lock up the entire machine; you can't just 
take the disk with you, as you can with floppy diskettes. 





There are basically two kinds of security that can help protect your 
software. The first, access security, is generally achieved through 
some method of multiple-level password protection for data files. 
The second, data encryption, requires encoding the actual data 
before they are written out to the disk. When needed by your pro- 
gram, the data must first be decoded. 


Access Security 


With this method of data security, you must know the correct pass- 
word in order to gain access to the data files. Password protection 
can be implemented at a general level (by requiring only one pass- 
word to gain complete control over the files, for example), or it can 
occur at multiple levels (one password might be needed to view se- 
lected data, a second to add new records, a third to change records 
and a fourth to change the passwords). 


[he level of security needed will depend on the nature of your soft- 
ware product and the expectations of your users. For guidance, you 
may want to look at password schemes in other software packages. 


Regardless of the level of password protection you choose, you 
must take precautions to protect the passwords themselves. This 
is best achieved by encrypting the password data file. 


Data Encryption 


With this method of security, data are modified by a constant or 
random algorithm before they are written out to a disk file. The 
data are decoded when they are read back into the program. Data 
encryption offers security outside normal program operation: un- 
less someone knows how to break the algorithmic code, the files 
cannot be read directly from the operating system, as an ASCIl text 
file could be, for example. 


An in-depth discussion of data security and encryption exceeds 
the scope of this manual. Many excellent reference materials on 
the subject are available, however, and you may consult these for 
additional information. 
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Manuals 


There are two principal types of manuals: user guides and reference 
manuals. User guides are generally more appropriate for teaching 
people how to use software. Reference manuals, more technical in 
nature, provide quick answers to questions about how the various 
functions of a program work. 


Ideally, both types of manual should be prepared for all systems. If 
the cost of producing both ts prohibitive, however, prepare a user 
guide; it is the more important of the two because the software's 
HELP function can often serve the role of a reference manual. If you 
do choose to write only a user guide, you might consider including 
an appendix that serves as a partial reference manual. 


The remainder of this section focuses on writing and organizing ef- 
fective user guides. However, because of the fundamental similari- 
ties between the two types of manuals, the following guidelines 
may be applied to writing effective reference manuals as well. 


A user guide that is clear and easy to use is key to acceptance of 
your software. An effective user guide must accomplish three 
things. First, and most important, it must present information ina 
logical and natural way that makes the learning process as easy 
and efficient as possible. Nothing will make someone lose interest 
in a program faster than a poorly organized or densely written 
manual. Second, it must be complete, yet concise; you don't want 
to present your readers with a cluttered compendium of irrelevant 
or insufficient information. And third, it must reinforce the learning 
process through practical examples, exhibits and appendices. 
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Developing User Guides 


The first objective in writing a user guide—to present information 
that is logical and easy to understand—can be achieved through a 
building-block approach to learning. Begin with the basics, teach- 
ing the novice the fundamentals of computer use and the skills 
necessary to manipulate the software. Do not be afraid to present 
the material at an elementary level, clearly defining the fundamen- 
tal elements of computer use. Reinforce these skills through exam- 
ples and hands-on experience. Once the basic skills have been mas- 
tered, the user may advance to the more sophisticated aspects of 
your software. Again, the advanced skills should be reinforced 
through practice until the user guide Is painlessly completed. 


Before you start writing your guide: 


e Put yourself in the user’s position. What is the skill level of your 
intended audience? How much time would you be willing to 
devote to learning this system? How would you like to see the 
material presented? 


e Identify the steps required to set up an application. Does there 
seem to be a natural order to the steps (e.g., enter data, make 
computations, print reports)? Are there some steps that seem 
out of order but still need to be presented early in the manual? 
Are there certain procedures, like installing DOS, that need to be 
performed before your software can even be used? 


e Develop an outline; then, have someone review it— preferably 
someone familiar with the software. Note any constructive sug- 
gestions offered. 


e Consider using case studies or tutorials as a very effective means 
of reinforcing the various topics discussed in the user guide. 


e Read Susan Grimm's book How To Write Computer Manuals for 
Users (Belmont, California: Lifetime Learning Publications, 1982). 
It contains many good suggestions for researching, organizing 
and writing manuals. 
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Case Studies 


A case study brings all the elements of a learning exercise together 
into one interrelated problem. Case studies can be used to demon- 
Strate the concepts presented in each chapter or group of program 
skills, or they can be used at the end to encompass all the skills cov- 
ered in the guide. Regardless of how they are used, case studies 
Should: 


e Be as true to life as possible. It is therefore important to identify 
your audience before developing a case study. 


e Avoid ambiguity and contradiction. You must thoroughly review 
each aspect of the case study and check its solution to ensure 
consistency with your program. 


e Be completely error free and easy to follow. 


Tutorial Diskettes 


A tutorial diskette contains programs that provide users with inter- 
active training experience. These programs: 


e Present information about your program on the screen. (In many 
respects they are like a HELP function.) 


e Ask the user questions about the material presented. After the 
user gives an answer, they determine whether the answer is 
accurate; if not, they provide the correct answer. 


e Allow the user to control his or her progress through a menu 
Structure. The user should be able to select topics sequentially 
Or in any order he or she desires, and the user should be able to 
return to a previous topic (to reinforce material) or jump ahead 
(to review new information). 


Develop a tutorial diskette for your program whenever possible. Be 
aware, however, that this is a very time-consuming project. Before 
beginning, you should always carefully weigh the advantages 
against the costs. 


The tutorial diskette for the Lotus 1-2-3 program provides addi- 
tional guidance. It is well constructed and may give you some good 
ideas for your own tutorial. 


46 


Writing Style 


There are four elements of writing style that you should consider in 
developing your user guide: audience, tone, tense and language. 


Audience 


Before you can write an effective user guide, you must know who 
your readers will be, what their general background is and how 
much training and microcomputer experience they have had. Only 
then will you know whether to address your manual to beginners 
or to a more advanced audience; only then can you decide how it 
should be presented. 


Unfortunately, making these determinations Is not always an easy 
task. It is generally safe to assume that your users are intelligent 
professionals who are novices with microcomputers. You should 
not assume that they have much advanced knowledge about mi- 
crocomputers. On the other hand, you must avoid “talking down” 
to them. 


Tone 


Write user guides in the second person: a conversational tone will 
give your readers the feeling that the manual has been written just 
for them. Sentences written in the second person are generally 
friendlier and more precise and direct. 


For example, here is a passage from a hypothetical user guide not 
written in the second person: 


The user should insert the system diskette into disk drive A and 
simultaneously press the ALT, CTRLand DELkeys to boot the pro- 
gram. Once booted, the program’s main menu, from which the user 
will make his or her initial selections, will appear. The user should 
select option b, SYSTEM BRIEFING, and read the information on the 
screen to learn more about the system. 
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Here is the same paragraph, written in the second person: 


Insert the system diskette into disk drive A, then press theALT , 
CTRL and DEL keys simultaneously to boot the program. Once 
booted, the program's main menu, from which you can make your 
initial selections, will appear. Select option 5, SYSTEM BRIEFING, 
and read the information on the screen to learn more about the 
system. 


See how much friendlier and more precise the second paragraph 
is? It speaks directly to you and leaves no doubt about what actions 
you are required to take when running the program. 


Tense 


Using the present tense goes hand in hand with the second person 
in creating a conversational tone in your writing. It makes your 
readers feel as if you are right there beside them, explaining each 
step. For example, consider the two paragraphs below, each written 
in a different tense. You will see that the second paragraph is much 
better than the first; not only is it more concise, but it also gives 
you a more comfortable feeling: 


(Future Tense) 


You will insert the system diskette into drive A before booting the 
software. Upon booting, a main menu screen will be displayed, from 
which you will be given eight choices. Assuming you will choose 
option 3, PRINT REPORTS, you will then select report number 2 to 
generate the Overtime Hours Summary. Upon completion of the 
report, you will exit the PRINT REPORTS option by pressing the 
ESC key. 


(Present Tense) 


Insert the system diskette into drive A and boot the system. When 
the main menu is displayed, select option 3, PRINT REPORTS. To 
print the Overtime Hours Summary, select report number 2. When the 
report finishes printing, press the key to return to the main menu. 
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Language 


Your writing is only as good as the words you use. The most effec- 
tive user guides follow a few basic language rules. Together with 
the other suggestions presented in this guide, the following rules 
will help you create very successful manuals: 


e Use short, simple words that will be easily understood by those 
who work with your manuals. To ensure that your ideas will be 
easily understood as well, use short, simple sentences and 
paragraphs. 


e Use active verbs, not passive verbs. Your manuals should state 
the action the user should take. 


e Avoid all jargon—technical jargon, computer slang, buzz words, 
abbreviations and acronyms. Use words that your audience will 
recognize. If you find that you must use certain technical or 
“inside” terms, be absolutely sure that you define them the first 
time they appear in the manual. 


Presenting the Text Material 


Besides mastering the basic rules for writing good user guides, you 
must consider how best to present the manual text. You should: 


e Determine the most appropriate method of presentation for your 
material. 


e Use illustrative examples that build on each other as they rein- 
force and unite the concepts presented. 


e Organize the information logically and coherently. 


e Develop an effective format with an appealing page style. 


Manuals 


There are a number of different ways to present the text material: 


e Prose. This method uses descriptive paragraphs to explain the 
procedures the user must follow to operate the program. 


e Cookbook. This technique follows the format of a cookbook: 
generally, each sentence begins with a verb and is short and to 
the point. 


e Dual column. This approach represents the interaction between 
the user and the program in separate columns on the page. The 
first shows a program request or prompt, and the second ex- 
plains, in short, simple sentences, the action the user must take. 


e Numbered instructions. This technique explains step-by-step 
how to use your software. Each step is preceded by a number. 


Many guides use a combination of these methods to explain how 
programs operate. In fact, this is often the most effective approach, 
since each method Is best suited to explaining different kinds of 
program tasks. 


The four different kinds of data-input methods (interactive, full- 
screen, spreadsheet and external files) and the menu-driven user in- 
terface (with optional command-driven interface) discussed earlier 
in this guide are each well suited to a particular type of presentation 
technique. These techniques are addressed below. 


User Interface 


Whether you implement a menu-driven interface, a command- 
driven interface or both, the instructional nature of a user guide re- 
quires that you present your material by task. Instead of explaining 
each menu option or command alphabetically or chronologically, 
present each one as It relates to a common illustrative example. 
Start with a simple example that presents the basic operations of 
the software. Then, build on the example by introducing the more 
advanced options and commands available in your program. 


Explaining how to perform specific tasks that are related to the 
example is best accomplished by using a combination of prose (to 
introduce the task) and numbered instructions (to explain how to 
achieve the results desired). Figure 13 shows a sample section from 
the user guide of AuditPlan, our hypothetical program. 
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FIGURE 13—SAMPLE PAGE FOR USER GUIDI 


AuditPlan has a number of built-in ratio-analysis functions that you 
Can use in your analytical-review process. These functions act on 
data that you defined using the trial-balance-preparation functions 
in the preceding chapter. You may use the following procedures to 
produce a report of standard financial ratios: 


Step 1— Select option 5, BALANCE TESTING, from the main menu 


Step 2—Select option 5, ANALYTICAL REVIEW, from the balance 
testing sub-menu. 


Step 3—Select option 1, FINANCIAL RATIOS, from the new 
Sub-menu. 


At this point, you will see the following menu: 


FINANCIAL RATIOS MENU 


Select Ratios 
Define New Ratios 
Compute Ratios 
Input Special Data 
Reports 


meus re 
8 i] ] L] a 


Step 4— Twenty standard financial ratios are available under option 
1, SELECT RATIOS. Select this option to view the list. 


Step 5—With the CURSOR DOWN key, move the cursor to the ratio 
heading ALL STANDARD. Press the ENTER key. (Later, we 
will show you how to select one or a group of standard 
ratios.) 


Step 6—The financial ratios menu, shown in step 3, will appear on 
the screen. Select option 3, COMPUTE RATIOS. 


Step 7— Now select option 5, REPORTS. You will be asked if you want 
the report displayed on the screen or printed. For now, press 
the S key to indicate the screen. 


The AuditPlan user guide would continue to build on this example 
until all the various options under the financial-ratios topic are ex 
plained. Then it would move on to other topics. This instructional 
approach for teaching someone how to use menus can be em- 
ployed just as effectively for explaining how to use a command 
driven program. 


While the combination of prose and step-by-step instructions can 
be used throughout the guide to explain the overall operation of 
the program, it is not always best for giving data-entry instructions. 
Often, a dual-column or screen/dual-column approach is more ef- 
fective. A discussion of this approach, as it relates to the four data- 
entry methods, follows. 


Interactive Data Entry 


As you may recall, the interactive data-entry method follows a 
question-and-answer format, with the user supplying the data 
requested by the program. Explaining this method tn prose can 
sometimes be very confusing. You can greatly clarify the expla- 
nation by taking the more structured dual-column approach. For 
example: 


FIGURE 14—DUAL-COLUMN APPROACH 


System Prompt or Question: Your Response: 


ENTER CLIENT NAME Enter any client’s name of up 
to 30 characters. You may 
use any alphabetic or numeric 
character. Press the ENTER 
key when ready to continue. 


ENTER YEAR END Enter the client’s current 

(MM-DD-YYYY) - year end. Enter the month 
first (01 =January, O2=Feb- 
ruary, etc.), then the day 
and the year. (Example: 
02-28-1984) Press the 
ENTER key when ready ~ 
to continue. 


ENTER CLIENT ADDRESS Enter the client's address, 
then press the ENTER key. 
You may use up to 35 al- 
phabetic or numeric char- 
acters. 
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This example is much easier to follow than the prone coal 
shown in figure 15 below: 


FIGURE 15—PROSE EXPLANATION 










The system will ask you to enter a clients name. You may «titer ary 
name of up to thirty characters, and you may use any alphabetie or 
numeric characters. Press the ENTER key when you are ready to 
continue. The system will then ask you to enter the client's yeur 

end in the form MM-DD-YYYY. Enter the month first (01 =January 
O2=February, etc.), then the day and the year. Press the ENTER kay 
to continue. Now you will be asked for the client's address. Enter an 
address of up to thirty-five characters, then press the ENTER key 
You may use any alphabetic or numeric character in the address. 
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Full-Screen Data Entry 


As you may recall, this method of data entry resembles completing 
a questionnaire. The user must enter responses in blank fields adja- 
cent to headings (refer to figure 10 for an example). A screen/dual- 
column approach, as follows, is most efficient for explaining this 
type of data entry. 


FIGURE 16A—FULL-SCREEN DATA ENTRY 


AuditPlan will display the following form when you select the 
CLIENT PROFILE option from the Audit Planning sub-menu. There 
are eight entries that you may make as needed. Each entry is ex- 
plained in detail following the sample screen shown below. Before 
you begin entering data, be sure that the system-control functions 
are active by pressing the SCROLL LOCK key until the word 
SYSTEM appears in the lower right-hand corner of the screen. 


Deloitte AuditPlan 
Haskins+Sells Colligan's Micros Inc. 
Client Profile 


CLIENT NAME : 
YEAR END (MM-DD-YYYY) : 


CLIENT ADDRESS : 
CITY, STATE, ZIP : 


INDUSTRY : 


AUDIT FEES FOR 1983 : 
14ée : 
1481 : 


} 
} 
} 


SA A AN AN AS 


PRESS Fb TO ENTER FORM AND MOVE ON. ESC TO END. 
CAPS NUN SYSTEM 
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FIGURE 16B—FULL-SCREEN DATA ENTRY 


Requested Entry: Your Response: 


CLIENT NAME Enter the client’s name, 
using no more than 30 char 
acters. You may use any al 
phabetic or numeric charac 
ter available. 


YEAR END Enter the date of the client's 

(MM-DD-YYYY) year end. Enter the month 
first (01 =January, 02=Feb- 
ruary), then the day and the 
year. You do not have to 
enter the hyphens; they are 
inserted by the program. 


CLIENT ADDRESS Enter the client's street or 
postal address, using any 
alphabetic or numeric char- 
acters available. This entry 
cannot be longer than 35 
characters. 


CITY, STATE, ZIP Enter the client's city, state 
and ZIP code. Use any com- 
bination of 35 alphabetic 
and numeric characters. 


INDUSTRY Enter a description of the 
client's industry, using no 
more than 35 characters. 


AUDIT FEES FOR 1983 Enter the audit fees for the 
1982 last three years, using no 
1981 more than 11 digits for 


each. DO NOT enter dollar 
signs Or Commas. 


At any time during the data-entry process you may escape by pressing 
the ESC key. When you have entered and edited all the information 
on this screen, press the F6 key to signal the program to accept the 
data and move on to the next function. 
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Spreadsheet Data Entry 


This method, which involves entering data into cells on a row/ 
column grid, can best be explained by numbered instructions. Here 
are a few guidelines: 


Because the information in a spreadsheet format is usually con- 
stant within either a row or a column (depending on how you 
define the row/column headings), all entries can be made in the 
Same manner: you can explain the data-entry process in terms of 
One row or column ata time, and you need tell your readers only 
how to enter the data in one cell of the row or column and how 
to move to the next cell. 


To explain the items that need to be entered into the worksheet 
cells, use a logical left-to-right or top-to-bottom approach. A hap- 
hazard sequence would cause the cursor to jump around on the 
worksheet. 


A section from our hypothetical user guide follows. Based on the 
example shown in figure 11, it explains the spreadsheet data-entry 
method in the format recommended above. The sample screen 
shown in figure 17A below accompanies step 2 of figure 1 7B. 


FIGURE 17A—SPREADSHEET DATA ENTRY 






Deloitte AuditPlan 
Haskins+Sells Colligan's Micros Inc. 
Lead Schedules 


b/ 30/84 







\e/31/83 he/ 31/84 








{Cursor 1s here} 






Circuit Boards 
4088 Microchips 
bSK RAM Chip Kits 
Power Supply 








Floppy Disk Drives 
LOMB Hard Disk Unit 


Monochrome Cards 











Colour/Graphics Cards 





CAPS NUM 





PRESS Fb TO COMPLETE. ESC TO EXIT. 
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FIGURE 17B—SPREADSHEET DATA ENTRY 


Now that you have defined the items that are going to appear on the 
lead schedule, you may enter the data amounts. Below is an example 
of how this might be done: 


Step 1—Select option 3, ENTER DATA, from the LEAD SCHEDULES 
sub-menu. 


Step 2— The program will display the blank spreadsheet shown 
below. Note that the column and row headings are dis- 
played at the top and left of the screen to make it easier for 
you to enter the data. We will explain how to enter data for 
each column. 


Step 3— Make sure the edit functions are active by pressing the 
SCROLL LOCK key until the word EDIT appears in the lower 
right-hand corner of the screen. 


Step 4— Position the cursor in the first column (12/31/83) of the 
first row (CIRCUIT BOARDS). Enter the inventory amount 
from the prior year’s trial balance. Press the ENTER key to 
place the amount into the cell. 


Step 5—Press the F1O key to move to the next row (8088 - 
MICROCHIPS). Enter the inventory amount as you did in 
step 4. Repeat steps 4 and 5 as needed to complete each 
row of data for the 12/31/83 column. 


Step 6—Use the F4and FU keys to move the cursor to the first cell 
in the second column (6/30/84). Enter the trial-balance 
amounts as of 30 June 1984. Repeat steps 4 and5 as 
needed to complete each row of data for this column. 


Step 7— Repeat step 6 for the third column (12/31/84). 


When you have entered all the data, hold the SHIFT key down 
while pressing the F6 key to save the information and return to the 
menu screen. 


External-File Data Entry 


Data entry through an external file is largely automatic: you tell the 
program where to find the data, and it will do the rest. The best ap- 
proach for explaining how to enter data in this manner is a combination 
of the prose and numbered-instruction methods. (See figure 13) 
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Organizing the Manual 


Every user guide should contain the following: 


e Front matter. The front matter includes a title page, copyright in- 
formation, a foreword (if appropriate) and a preface. 


e Table of contents. A general table of contents should list all 
chapter headings and major subheadings. 


e “How To Use This Manual.” This section should explain how the 
manual is organized, how to install the operating system on the 
program diskettes and how to back up program diskettes. It 
should also explain the standard conventions that are used (how 
keystrokes are represented, how instructions are given to users 
and how files are named, for example). 


e Introduction. The introduction explains basic information about 
the program and its uses. 


e Body text. This includes all body text and a detailed table of con- 
tents for each chapter. 


e Appendices. These should include function-key definitions, a 
Summary of error messages, a tree diagram of system-menu op- 
tions, a reference guide to the command sub-system (if neces- 
sary), standard IBM printer-control codes and an external data- 
file interface. 


e Index. An index should be included, particularly if the manual is 
long or complicated. This is a helpful addition to any manual— 
especially a reference manual— because it gives the user immedi- 
ate access to any piece of information. 


Some of these sections may be unnecessary — or too costly — for in- 
clusion in your guide. However, the more sections you include, the 
more helpful your user guide will be. 


The major sections of your guide should be presented in the order 
in which they are shown above. Except for the front matter and 
some of the appendices (which are described below), each section 
is basically self-explanatory. 
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Front Matter 


Front matter consists of all the printed information that usually ay 
pears before the first chapter or section of the manual—generally 
title page, copyright page, preface and table of contents: 


e Title page. The title page contains the complete title of the man 
ual, the firm’s name (as author) and the name of the publisher (in 
most cases this is the firm). The title page is the first (right-hand) 
page. 


e Copyright page. The copyright page appears on the reverse side 
of the title page and contains the copyright notice in the follow- 
ing form: 


Copyright © 1984 by Deloitte Haskins & Sells 


The copyright page also contains the publication date. This infor- 
mation can appear at the bottom of the title page as well. 


e Preface. The preface should discuss the purpose and content of 
the software and the user guide. It should be as brief as possible 
and should not duplicate information presented in the introduc- 
tory chapter. In addition, you may use the first person and the 
second or third (but do not mix the second and third when refer- 
ring to your users). 


e Table of contents. The table of contents is a list of the section 
headings and major section subheadings. It should be a brief but 
useful guide to the contents of the manual—it should not be so 
detailed that it functions as an index. 


Appendices 


Below is a description of the appendices, along with examples to 
illustrate those you may not be familiar with. You may also find it 
helpful to review the user guides of other software producers to 
see how they have written these sections. 


Function-Key Definitions 


These are illustrations, like those used in figures 2 and 3, explaining 
how the function keys have been defined. Short, narrative descrip- 
tions of each key should follow the illustrations. 
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Organizing the Manual 


Summary of Error Messages 


This appendix is simply a list of all error messages that your system 
produces. Place them alphabetically in a dual-column format, fol- 
lowing the style of the IBM BASIC manual. 


Tree Diagram of System Menu Options 


A tree diagram demonstrates the structural relationships between 
the various menu options in a program. The diagram can help users 
determine what action(s) must be taken in order to get from one 
point in the program to another. 


FIGURE 18—TREE DIAGRAM OF MENUS 


MAIN MENU SUB-LEVEL 1 SUB-LEVEL 2 SUB-LEVEL 3 


Audit Planning Fee Projection 
Interim Schedule 
Final Schedule 


Audit Administration Budget/Time Analysis Enter Budget 
Staff Hours 
Analysis Reports 


Fee Summary Input Charge Rates 
Foreign Exchange Input Rates 
Compute US Dollars 


Reports 


Participating Offices Assignments Correspondence 
Due Dates Schedule 
Reports 


Internal Control System Description 
Control Questionnaire Edit Responses 
Clear All Responses 
Define Special Questions 


Evaluation 


Reports System Description 
Questionnaire Responses 
Personnel List 
Critical Combinations 
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Reference Guide to the Command Sub-System 


If you are implementing a command sub-system, youl slid oy 
ally include a short reference guide as an appendix. (I lhiis ine 

be necessary, however, if you are preparing a separate telein: 
manual.) Like the summary of error messages, this guide lili 
present commands alphabetically in a dual-column format [hi 
description of each command should be as brief as possible mid 
should explain: 


e What the command ts used for 


e Where the command takes the user, in terms of the interaction 
of the program and its menus. For example, most command sub 
systems are superimposed on the menu structure. When the 
user selects a task, the program determines where in the menu 
Structure he or she needs to be to carry out the task. To explain 
how tasks interface with the menu structure, you may want to 
refer the user to discussions that appear earlier in the user guide 
(such as that on data entry). 


e What options are available when giving the command 


e |The syntax of the command 


Control Codes for the Standard IBM Printer 


For convenience, present in a dual-column format some of the con- 
trol codes commonly used with the IBM printer (which is in the 
Epson MX-80 series). In this appendix you should include codes for: 


e Compressed print 
e Enlarged print 

e Enhanced print 

e Print width 

e Page length 


e Top-of-page indicator 


External Data-File Interface 


Numbered instructions provide the best means of explaining how 
to use the external data-file interface, which is discussed later in 
this guide. 
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Organizing the Manual 


Separate Reference Manuals 


You may want to provide a separate reference manual for some of 
the programs that you write. There are two ways to organize the 
material in a reference manual. You can present each system com- 
mand alphabetically, beginning each command description ona 
new page and including the appendices discussed above. Or, you 
can group system commands by function, separating them into 
sections for input commands, report commands and housekeeping 
commands, for example. Present each command alphabetically in 
its section and include the appendices. A viable alternative, if you 
Cannot produce a complete manual, is to provide important infor- 
mation on a concise reference card. (See “Pocket Reference Card,” 
page 65) 


Overall Manual Appearance 


Some guidelines for the general appearance of your manuals follow. 


Page Presentation 
e Material should be printed on both sides of the paper. 


e Paper should be 5 1/2 by 8 inches and hole-punched to fit into 
the three-ring binder that is standard for the IBM PC manuals. 


e Each section should begin on a right-hand page that contains a 
detailed table of contents. 


e The first page of text that begins each section should also be a 
right-hand page. If the section's table of contents is only one 
page, leave the next left-hand page blank. 


e Use adequate leading (white space) between paragraphs, chapter 
titles and headings to make your manual easier to read. 


e Place page numbers on the lower outside corner of each page, 
flush with the margin. The page number should be in the form 
N.nn (e.g., page 4.27), where N represents the section number, 
and nn represents the page number within the section. Use cap- 
ital letters to identify the section numbers for appendix pages 
(e.g., page B.15). 


e Figures and tables should be numbered like pages (e.g., Figure 
3.2 or Table 12.8). Place figure headings flush left above the fig- 
ures, and table headings flush left above the tables. 
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e Consider including the publication date on each page of the 


manual so your readers will know how current the material is 
Place the date in the lower corner opposite the page number 
You may wish to include a page-number cross-reference index 
with the appendices. 


e The manual should be typeset if possible. 


Headings 


To achieve a streamlined appearance for your guide, use no more 
than four levels of headings. Because it is the most important, a 
level-one head should be reserved for the title of a new section and 
should appear at the top of the page. 


In typeset manuals level-one heads should be the largest and 
should be set in bold-face type. They may be flush with, or extend 
two picas into, the left margin. 


Type size, weight and position can all be used to show the relative 
importance of headings. Four levels of heads that are appropriate 
for a manual set in 11-point Univers type, such as this one, are iI- 
lustrated below: 


FIGURE 19—TYPESET HEADINGS 


This Is a Level-One Heading 


(Set in 14-point Univers bold, upper/lower case; level-one heads 
may hang two picas in the left margin.) 

This Is a Level-Two Heading 

(Set in 11-point Univers bold, upper/lower case, positioned flush 
left with text.) 

This Is a Level- Three Heading 

(Set in 11-point Univers medium, upper/lower case, positioned 


flush left with text.) 


This Is a Level-Four Heading. (Set in 11-point Univers medium, 
upper/lower case, integrated with text.) 
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Organizing the Manual 


For manuals that must be typewritten, headings provide an essen- 
tial medium for preserving white space on the page. Accordingly, 
they should be preceded by three returns and followed by at least 
two (three or more are appropriate for level-one headings). The four 
levels should appear as follows: 


THIS IS A LEVEL-ONE HEADING 
THIS IS A LEVEL-TWO HEADING 
This is a Level-Three Heading 
This is a Level-Four Heading 


Representing Keys in User Guides 


The wide variety of ways in which keys are represented in software 
manuals has perplexed many a user. To avoid confusion, be as lit- 
eral as possible when telling your readers which keys need to be 
pressed to carry out specific actions. For example, the instruction, 
“Type EXECUTE RULE and then press the ENTER key,” is clear and 
much less likely to result in a keystroke error than a phrase such as, 
“Type EXECUTE RULE <CR>.” Even if you have properly explained 
that “<CR>” means “press the ENTER key,” some users will over- 
look the explanation and literally type all the characters, including 
<,C,Rand>. 


Here are some additional guidelines for representing the IBM PC's 
various keys: 


e Print all the letters, numbers and characters that must be typed 
on the keyboard in a colour, like green, to distinguish them from 
the text (which is generally printed in black). If you cannot use a 
colour, use bold or italic type and capital letters. If none of these 
aids are available, you will have a difficult time presenting the 
material clearly. 


e For typeset material, consider using icons (graphic symbols) to 
represent those keys that are identified by symbols on the IBM 
PC keyboard. These are the SHIFT, TAB, BACKSPACE and 
ENTER keys. Otherwise, use the words themselves. 


e Avoid enclosing keystroke directions in quotes, single quotes, 
brackets or other delimiting characters. If you do, someone will 
invariably type the delimiters along with the keystrokes. 
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Function-Key Template 


lf your software-development budget allows, include with your 
manual a function-key template. This plastic keyboard overlay pro 
vides an easy-to-use guide to the function-key definitions. An 
example follows. 


FIGURE 20 —FUNCTION-KEY TEMPLATE 


Restore 
field 


Insert | Delete 
line line 


Column} Column 
<_—— | —_—_i- 


PlusPlan Deloitte Haskins+Selis 





Pocket Reference Card 


If you have implemented a command sub-system, you might also 
consider providing a pocket reference card —a folding panel card 
that duplicates the information in the command reference guide in 
the appendices. 


Other Considerations 


We have now covered a variety of topics that will help you develop 
user-friendly programs. There are a few other ingredients essential 
to creating programs that are easy to learn, enjoyable to use and 
well documented. 


Support for Hard Disks 


All your programs should support both the IBM PC and the IBM PC 
XT. The XT includes a 10-megabyte hard-disk storage unit, which 
the IBM operating system addresses as drive C. Your program must 
be able to support the use of drive C for data purposes. To accom- 
plish this, incorporate a housekeeping task that will allow users to 
specify which disk drive will be used for the data. Here are some 
guidelines: 


e Make sure the file names used in your program do not include 
the disk-drive letter as a fixed character; it must be a variable. 
For example, in BASIC do not use a statement like: 


OPEN “B:FILE1.DAT” FOR INPUT AS #2 


Instead, set a string variable equal to the drive letter that you 
specified when you were running the program's housekeeping 
tasks. Assume that this was accomplished with the statement: 


INPUT DRIVE$ 


Use a second string variable for the file name you enter while 
running the program. For example: 


INPUT FNAME$ 


Your program can then open the file using the following 
Statements: 


FILES=DRIVES+FNAME$ 
OPEN FILE$ FOR INPUT AS #2 


e Tocall another program segment or file (like a HELP file) from the 
system diskette during program operation, do not specify a drive 
letter for this file in the program statement. The operating system 
will then assume that the program Is requesting the file from the 
system default drive— the one shown in the DOS prompt. (For 
example, if the DOS prompt is A>, A is the default drive.) This will 
allow you to copy the system disk to a hard disk or a RAM disk 
without making any program modifications. 
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External Data-File Interface 


The most useful and versatile programs are those that can ex- 
change data with other computer programs. Unfortunately, it is 
difficult to achieve this objective since all programs do not store 
data in the same format. Thus, your program must be capable of 
rearranging the data into a compatible format that can be read by 
other programs. 


Not all programs have information that is useful to other programs, 
however. For example, a memorandum prepared with a word pro- 
cessor is probably not useful in a financial-forecasting program. 
Accordingly, you should first determine whether data used by your 
program may be of use to others and whether the data your pro- 
gram needs can be obtained from others. If this is the case, you 
should provide a means of exchanging information with other 
programs. 


There are two ways to accomplish this. First, having determined 
which programs may need your data (and vice versa), you can pro- 
vide special methods for interchanging data with these programs. 
This is somewhat short-sighted, however, because you have no 
way of determining what future programs will also need to inter- 
face with yours. You will be continually modifying your program to 
handle new programs. Fortunately, the alternative is more flexible. 


Use a standard data-interface method that allows unrelated pro- 
grams to share data. The only one in common use is the Data Inter- 
change Format (DIF) developed by Software Arts, Inc. Technical 
specifications for the DIF can be found in a number of software 
packages, including VisiCalc. Or you may order the specifications 
directly from the DIF Clearinghouse, P.O. Box 526, Cambridge, MA 
02139 USA. (There is a small fee to cover reproduction and han- 
dling costs.) 


System-Installation Procedures 


It is often convenient to have PC-DOS command files on your pro- 
gram diskette; your software can then be booted directly, without 
having to boot PC-DOS first. Unfortunately, IBM does not allow soft- 
ware producers to license the IBM PC-DOS command system for 
distribution with software packages. Accordingly, you must develop 
your own procedures for copying PC-DOS onto your program 
diskettes. ° 
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Other Considerations 


The easiest way to do this is to incorporate the installation proce- 
dures with those for the system backup. The installation procedures 
follow a pattern like the one below: 


e A batch file called INSTALL is included on the program diskette. 


e Boot PC-DOS, then insert the program diskette into drive B. Type 
B:INSTALL and press the ENTER key. 


e The INSTALL procedure then uses the PC-DOS disk to format a 
new diskette (including the system files) on drive A and to copy 
the program files from disk drive B to the newly formatted dis- 
kette in drive A. 


e Throughout the INSTALL process, follow instructions to remove 
and insert certain diskettes that are needed to perform the 
installation. 


e If the program is going to be distributed outside Australia, the 
INSTALL procedure must also copy the appropriate IBM 
keyboard routines from PC-DOS to the new program diskette it 
IS Creating. 


Copy-Protection Schemes 


There are many arguments for and against copy-protecting pro- 
gram diskettes. Generally, the protection provided by these meth- 
ods is limited and can be easily circumvented if desired. Also, the 
importance of having the ability to back up program diskettes 
nearly always outweighs the costs of software piracy. Therefore, 
we do not recommend that you take any measures to copy-protect 
your program diskettes. 


As an alternative, use software licence agreements to protect your 
interest in the software you develop. Review some of the licence 
agreements currently being used by software producers, and 
pattern your own after theirs. You should also consult a solicitor 
regarding the legality of any such agreements. 
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Access security, 43 
Active-display screen, 15, 18-20, 
23, 24, 28, 32, 37 
sections of, 18-20 
ALT key, 14, 47, 48 
Appendices, for user guides, 44, 
58-61 
control codes for the standard 
IBM printer, 58, 61 
external data-file interface, 61 
function-key definitions, 59 
reference guide to the com- 
mand sub-system, 61 
Summary of error messages, 60 
tree diagram of system menu 
options, 60 
Audience, 45. See a/so Writing 
Style 
AuditPlan, 9, 20, 21, 24, 25, 28, 
32, 50-51 


BACKSPACE key, 13, 64 

Blinking display technique, 39 

Body text, for user guides, 58 

Boot screen, 15, 18 

Building block approach to learn- 
ing, 45 


CAPS LOCK key, 19 
Case studies, 46 
Cells, 31-32 
Character delete key, 12 
Character insert key, 12 
Colour 
for user guides, 64 
for video technique, 16, 24, 35. 
See a/so Video display tech- 
niques 
Columns, 19-20, 31-32, 56. See 
also Rows 
Command sub-systems, 24, 26 
reference section for, 26, 61 
Compound errors, 38. See a/so 
Error trapping; Errors and 
error messages 


Control codes 
for IBM printer, 58, 61 
for printers, 7 
sending of, 40 
Cookbook method for presenting 
text, 5O 
Copy protection, 68 
Copyright pages, for user guides, 
59 
CTRL key, 14 
Cursor control keys, 7, 8, 12, 13, 
14, 24, 26, 37, 39 


Data encryption, 43 
Data-input methods, 28-33 
external file, 28, 33, 50 
full screen, 29, 50 
interactive, 28, 50 
spreadsheet, 31, 50 
Date and time, 16-18, 28, 30, 42 
DEL key, 13 
Developing user guides, 45-46 
Display diskette directory, 10 
Display techniques. See Video 
display techniques 
Dual-column method for present- 
ing text, 50, 52-54, 60, 61 


Edit functions, 9, 11-13, 19, 28, 
29, 30, 32, 37 

END key, 14, 24, 35, 39 

ENTER key, 13, 22, 25, 26, 28, 30, 
31, 32, 37, 64, 68 

Error trapping, 6, 12, 36-39 

Errors and error messages, 12, 19, 
20, 36-39, 58, 60, 64 

ESC key, 13, 22 

Exit system, 10 

External data-file interface, 58, 
61,67 

External-file data entry, 33, 57. 
See a/so Data-input methods 
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Field testing, 36 

Figures, for user guides, 62 

Front matter, for user guides, 58, 59 

Full-screen data entry, 29, 50, 
54-55. See a/so Data-input 
methods 

Full-screen overlays, 24-25. See 
also Windows 

Function-key template, 65 

Function keys, 7-13, 30, 59. See 
also Edit functions; System- 
control functions 


Graphics, 16, 41 


Hard disk support, 66 

Headings, for user guides, 63-64 

Help function, 7,9, 11, 13, 19, 25, 
34-35, 44, 46 

Hex codes, 41 

Highlighted video, 16, 19, 24, 26, 
35, 39, 40. See a/so Video 
display techniques 

HOME key, 14, 24, 35, 39 


IBM display screen, 19-20 

IBM PC, 5, 6, 7, 8, 27, 40, 43, 62, 
64, 66,67, 68 

Implementing function sets, 12 

Indexes, for user guides, 34, 35, 58 

INS key, 14 

INSTALL file, 67-68 

Interactive data entry, 28, 50, 52. 
See a/so Data-input methods 

Introductions, for user guides, 58 

Invalid keystrokes, 36, 37. See 
a/so Error trapping; Errors 
and error messages 

Invalid user responses, 19, 36-37. 
See a/so Error trapping: 
Errors and error messages 
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Keyboard usage, /-14 


Language. See Writing style 

Licence agreements. See Copy 
protection 

Line/delete, column/right, 11 

Line/insert, column/left, 11 

Lotus 1-2-3, 31, 34, 46 


Manuals, 44-65 
Development, 45-46 
Organization, 58-65 
Presentation of text, 49-57 
Writing style, 47-48 
Menu-driven software, 21, 26, 50 
Menus 
general guidelines for, 21-22 
levels of, 21, 26 
main, 21 
selection of, by cursor, 25 
selection of, by single key- 
Stroke, 22, 25 


NUM LOCK key, 14, 19 

Numbered-instructions method 
for presenting text, 50, 57 

Numeric-data entry, 7,8 

Numeric keypad, 7,8, 11, 12, 13, 
14, 24 


Page length, for printers, 40 

Page presentation, for user 
guides, 62-63 

Page width, for printers, 40 

Partial-screen overlays, 24-25. 
See also Windows 

Passwords, 43 

PGDN key, 14, 24, 35, 39 

PGUP key, 14, 24, 35, 39 

Pocket reference cards, 62, 65 

Prefaces, for user guides, 59 


Printer control codes. See 
Control codes 
Printer support, 40-41 
Programs 
identification screens for, 16 
names of, 16 
processing of, 10, 17, 21, 23, 
38, 39 
wrap-up of, 23 
Prose method for presenting text, 
50, 53,57 


Real-time clocks, 18 

Reference cards. See Pocket ref- 
erence cards 

Reference manuals, 62. See a/so 
Manuals 

Restore field function, 11, 37 

Reverse video, 16, 24, 39, 59. 
See a/so Video display 
techniques 

Rows, 19-20, 31-32, 56. See a/so 
Columns 


Sample page for user guide, 51 
Screens 
speed of, 27, 34 
usage and presentation of, 
15-27 
SCROLL LOCK key, 12 
Scrolling, 24 
Security, 43 
Sending control codes. See 
Control codes 
SHIFT key, 13, 64 
Special display modes. See Video 
display techniques 
Special hex codes. See Hex codes 
Special-purpose keys, 7 
Split screens, 24-25 
Spreadsheet data entry, 11, 28, 
30, 31-33, 36, 50, 56-57. See 
also Data-input methods 


Standard report formats, 42 

System-control functions, 9-10, 
54 

System errors, 37. See a/so Error 
trapping; Errors and error 
messages 

System-installation procedures, 67 


Table of contents, for user 
guides, 58, 59 

Tables, for user guides, 62 

Tense. See Writing style 

Text material, presentation of, 
49-57 

Title pages, for user guides, 59 

Tone. See Writing style 

Tree diagram of system menu 
options, 60 

Tutorial diskettes, 46 

Typeset manuals, 63 


UNDO last operation, 10 
User friendliness, 5, 9, 24, 34-35, 
36, 66. See a/so Help 
function; Error trapping 
User guides. See Manuals 
User interface, 50-51 
Users 
experienced, 21, 26 
novice, 4/7 


Video display techniques, 24, 27. 
See a/so Colour video; 
Highlighted video; Reverse 
video 

VisiCalc, 31, 67 


Windows, 10, 19, 24 
Writing style, 47-49 
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Developing good microcomputer software takes a great deal of 
time and energy. so the last thing you want to happen is to make 
such an investment in a program, only to have no one use it. The 
reasons for rejection are numerous. Perhaps your software is not 
easy to use, or the learning Curve is too high. Maybe the reports 
are not flexible enough, or the manual is confusing. Whatever the 
reason, the result is the same: you will have wasted valuable time 
and energy on software that lies idle. 
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people will enjoy using. It offers a comprehensive set of 
guidelines for developing user-friendly software that possesses 
consistent operating characteristics. Keyboard usage, representing 
keystrokes in manuals, screen usage and presentation, error 
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are among the items covered. 


Deloitte Haskins & Sells are one of Australia’s largest accounting 
firms offering a wide variety of business and financial management 
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bodies to small businesses and private individuals. 


